<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">

<html lang="en">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>Bing BlackBerry SDK Documentation</title>
	<style type="text/css">
	  h1, h2, h3, h4 {
		  font-family: Arial, sans-serif;
	  }
	  code {
	    border-left: solid 3px #999;
	    display: block;
	    margin-left: 25px;
	    padding: 10px 15px;
	    white-space: pre;
	  }
	</style>
</head>
<body>
<h1>Bing BlackBerry SDK Documentation</h1>
<h2>Adding Bing to Your Application</h2>
<h3>Using Bing in a BlackBerry Application</h3>
<p>The Bing BlackBerry SDK can be built as an embedded Library that can be added to any 
    BlackBerry application.</p>
<h4>Building the Library</h4>
<ol>
	<li>Open Eclipse.</li>
    <li>In &quot;Project Explorer&quot; Right-Click.</li>
    <li>Choose Import-&gt;General-&gt;Existing Projects 
        into Workspace.</li>
    <li>Import the <b>bbing</b>.</li>
</ol>
<h4>Adding the Library to your BlackBerry Project</h4>
<ol>
	<li>Right-Click the project that will use the Bing BlackBerry SDK and select 
        Properties.</li>
    <li>Choose the Java Build Path item.</li>
    <li>Select the Projects tab.</li>
    <li>Choose Add and then check off the <b>bbing</b> project.</li>
    <li>Select OK.</li>
</ol>
<p>When using the Bing BlackBerry SDK as a Library, you can import the necessary Bing objects into your application by using the Bing 
    Library prefix:</p>
<code>import bing.*;</code>
<p>Note that you can also compile the Bing source files directly into your 
    BlackBerry App in addition to using a compiled Library.</p>
<h2>Querying Bing</h2>
<p>All searches must be invoked using the search method on a Bing object.</p>
<h3>Initializing the Bing Object</h3>
<p>The Bing object is used to dispatch search requests to the Bing API. In order to initialize the Bing object and use the Bing API you will first need to obtain a Bing Application ID. You can easily sign up for one at the <a href="http://www.bing.com/developers">Bing Developer Center</a>.</p>
<code>Bing bing = new Bing(&quot;MY_APP_ID&quot;);</code>
<h3>Performing a Basic Single Source Type Query</h3>
<p>To perform a basic web search, you first must instantiate a request object, set any parameters, and then perform the search using the Bing object.</p>
<code>BingWebRequest request = new BingWebRequest();
request.setFileType(&quot;pdf&quot;);

// Performs a synchronous request
BingWebResponse response = (BingWebResponse)bing.search(&quot;Bing API&quot;, request);
 
// Do something interesting with the results...</code><h3>Querying Multiple Source Types at Once</h3>
<p>With the Bing API, it is possible to search multiple source types using a single HTTP request. In the Bing 
    BlackBerry SDK, this is called a BundleRequest because it bundles together other request objects. To perform a bundle request, create individual request objects and then add them to a BundleRequest object.</p>
<code>BingWebRequest webRequest = new BingWebRequest();
BingImageRequest imageRequest = new BingImageRequest();

imageRequest.setFilters(&quot;Size:Width:320&quot;); // Set request specific options

BingBundleRequest bundle = new BingBundleRequest();
bundle.addRequest(webRequest);
bundle.addRequest(imageRequest);

BingBundleResponse response = (BingBundleResponse)bing.search(&quot;Bing API&quot;, bundle);

BingResponse[] responses = response.responses();
for(int i = 0; i &lt; responses.length; i++)
{
    BingResponse singleResponse = responses[i];
    BingResult[] results = singleResponse.results();
    for(int k = 0; k &lt; results.length; k++)
    {
        BingResult result = results[k];
        // Do something interesting with the results...
    }
}</code><p>Alternatively, you can also pass a list of several requests into the BingBundleRequest initializer. This can provide more concise code.</p>
<code>BingBundleRequest bundle = new BingBundleRequest(new BingRequest[]{ request1, request2, request3 });</code>
<p>Note that when using a bundle, only the top level request options (version, 
    market, etc.) within the Bundle will be respected. The top level request options 
    of all requests passed into the bundle will be removed. Because of this, it is 
    suggested that you create new request objects for each BingBundleRequest object.</p>
<h4>Parsing Results From a Bundle Response</h4>For BingBundleResponse objects, the results function will return null, instead 
    use the responses function, it will return an array of BingResponse objects each corresponding to a single source type. An example of how to access individual results from each response can be seen in the previous code example.<h3>Performing Asynchronous Requests</h3>In some cases it may be desirable to perform an asynchronous search. Asynchronous 
    requests are especially useful when creating a BlackBerry application. To perform an asynchronous search, pass in a delegate object that implements the BingAsyncRequestNotification informal interface to the search(String,BingRequest,BingAsyncRequestNotification) method. Everything else is exactly the same.</p>
<code>public class MySampleDelegate implements BingAsyncRequestNotification
{
    public void receiveBingResponse(BingResponse response)
    {
        // Do something interesting with the results...
    }
}

...

MySampleDelegate myDelegate = new MySampleDelegate();
BingWebRequest webRequest = new BingWebRequest();

bing.search("Bing API", webRequest, myDelegate);</code><h2>Handling Errors</h2>
<p>If an error is encountered while querying the API, a null value will be returned instead of a BingResponse object. The most common cause for this is an invalid Application ID. However, an error can also be caused by setting an invalid parameter in one of the BingRequest objects.</p>
<p>For more detailed error messages, compile the Bing Library in with the BING_DEBUG 
    which can be set in the Bing Library&#39;s BlackBerry_App_Descriptor.xml.</p>
    <ol>
        <li>Open <b>bbing</b>&#39;s application descriptor (BlackBerry_App_Descriptor.xml).</li>
        <li>Choose the Build tab on the bottom of the screen.</li>
        <li>Click the Add button under the &quot;Preprocessor Directives&quot; section.</li>
        <li>Type BING_DEBUG into the pop-up that comes up and select OK.</li>
    </ol>
    <p>
        If Bing Library has BING_DEBUG defined then a couple extra functions appear in 
        the Bing class. These classes are to allow the developer to handle full error 
        messages by setting their Bing object to return a BingError if an error occurs. 
        The BingError object will be returned in the BingResponse to developer&#39;s query.</p>
<h2>Available SourceTypes</h2>
<p>Currently, the Bing BlackBerry SDK supports the following Bing SourceTypes:</p> 
<ul>
  <li>Ad Request</li>
    <li>Image Request</li>
    <li>InstantAnwser Request</li>
    <li>MobileWeb Request</li>
    <li>News Request</li>
    <li>Phonebook Request</li>
    <li>RelatedSearch Request</li>
    <li>Spell Request</li>
    <li>Translation Request</li>
    <li>Video Request</li>
    <li>Web Request</li>
</ul>
<p>Each of the available source type result objects has its properties defined in the <a href="http://msdn.microsoft.com/en-us/library/dd250847.aspx">Bing API Documentationation</a></p>The properties of the result objects can be easily accessed using dot notation (ex: myWebResultObject.getUrl()).</p>
<h2>Unified Search</h2><p>As of BlackBerry OS 6.0, a new search API has been implemented known as Unified Search. This API allows users and developers to search the web, 3rd party apps and data, and the BlackBerry handheld itself for information.</p>
<p><b>bbing</b> has a Unified Search implementation built in as of 2.2.1, this allows for simple setup and cleanup of what is known as an <a href="http://www.blackberry.com/developers/docs/6.0.0api/net/rim/device/api/unifiedsearch/searchables/ExternalSearchProvider.html">ExternalSearchProvider</a>.
This creates a single search icon that allways appears when a search is performed, when the icon is selected the &quot;External Search Provider&quot; performs its search and returns the results on its own UI.</p>
<p>Using <b>bbing</b>, the developer creates a SearchProviderOptions and registers it with UnifiedSearch. That's it, <b>bbing</b> does the rest.</p>
<h3>Creating a SearchProviderOptions</h3>
<p>This is very easy. SearchProviderOptions is a special wrapper around a callback called SearchCallback. Implement SearchCallback, pass it into a SearchProviderOptions and this step is done.</p>
<code>SearchProviderOptions options = new SearchProviderOptions(new new SearchCallback()
{
    //SearchCallback implementation
});</code>
<p>The options provider should be saved because it will be used to register and unregister your search system.</p>
<h3>Registering SearchProviderOptions</h3>
<p>This is very easy:</p>
<code>UnifiedSearch.registerSearchProvider(options);</code>
<p>That's it! Before this when you did a search nothing showed up. Now if you do a search, a icon appears that can be selected and (if a search UI has been implemented) the UI with the results is displayed</p>
<p><strong>Note:</strong> One element of SearchCallback is a function called <i>updated</i>. This function can be used to alert registerSearchProvider that the name and/or icon of the provider has been updated. This does not automatically occur, if the name or icon get updated the devloper can call registerSearchProvider again and pass in the same SearchProviderOptions. As long as the options provider is not in use it will be updated with the new icon and name.</p>
<p>Also remeber to unregister your SearchProviderOptions when it is no longer needed. Failing to unregister your SearchProviderOptions can cause unpredictable operations to occur or multiple search options to appear when a search is performed.</p>
<p>To create a singleton search implementation, follow the following developer article &quot;<a href="http://docs.blackberry.com/en/developers/deliverables/17953/Ensure_device_runs_single_instance_1214527_11.jsp">Ensure that a device runs a single instance of your application</a>&quot; adapting the code so that instead of the operation occuring at search time it occurs at register time.</p>
<h3>Unregistering SearchProviderOptions</h3>
<p>This is extremely easy again:</p>
<code>UnifiedSearch.unregisterSearchProvider(options);</code>
<h3>Other Unified Search notes</h3>
<p>A couple small requirements for using Unified Search exist:
<ol>
    <li>Application signing is required. If no signing is desired then use the define <i>NO_SIGNING</i>. This will disable the need for application signing but will also disable Unified Search support.</li>
    <li>Requires OS/API 6.0 or higher. This is a given, luckily Unified Search support is determined internally. It determine is Unified Search is supported at runtim call UnifiedSearch.isSupported().</li>
</ol>
<h2>Happy Bing-ing!</h2>
</body>
</html>
